used by computers and GPS receivers.
<ulink url="http://www.topografix.com/gpx.asp">GPX</ulink> defines a
standard in XML to contain all the data, but there are too many
-programs that don't understand it yet and too much data that are in an
+programs that don't understand it yet and too much data in
alternate formats.
</para>
<para>
-Perhaps you have an Explorist 600 and your friend has a StreetPilot 2720.
+Perhaps you have an <link linkend="fmt_magellanx">Explorist 600</link> and your friend has a <link linkend="fmt_garmin">StreetPilot 2720</link>.
You've collected a a list of your favorite locations as waypoints and you'd
-like to be able to share them. Unfortunately, his copy of Garmin Mapsource
-won't read data created by your copy of Magellan Directroute. What you need
+like to be able to share them. Unfortunately, his copy of <link linkend="fmt_gdb">Garmin Mapsource</link>
+won't read data created by your copy of <link linkend="fmt_mapsend">Magellan Mapsend DirectRoute</link>. What you need
is a program that converts data bewteen the two programs.
</para>
<para>
<section id="style_street_addr">
<title>STREET_NAME</title>
-<para>Street address including house number.</para>
+<para>Street address including house number. Notice that this is not used for any geocoding, it's merely textual description associated with a position.</para>
<para>example:<screen format="linespecific">STREET_ADDR, "", "%s"</screen></para>
</section>
<section id="style_city">
<title>CITY</title>
-<para>The name of a city. Sometimes part of "Points of Interest".</para>
+<para>The name of a city. Sometimes part of "Points of Interest". This is simple textual data associated with a position, no geocoding will be done..</para>
<para>example:<screen format="linespecific">CITY, "", "%s"</screen></para>
</section>
<section id="style_country">
<title>COUNTRY</title>
-<para>.......</para>
+<para>The name of a country associated with a position.</para>
<para>example:<screen format="linespecific">COUNTRY, "", "%s"</screen></para>
</section>
<section id="style_facility">
<title>FACILITY</title>
-<para>.......</para>
+<para>The name of a facility to associate with a position.</para>
<para>example:<screen format="linespecific">FACILITY, "", "%s"</screen></para>
</section>
<section id="style_phone_nr">
<title>PHONE_NR</title>
-<para>.......</para>
+<para>A phone number associated with a position. This is just textual data attached for convenience.</para>
<para>example:<screen format="linespecific">PHONE_NR, "", "%s"</screen></para>
</section>
<section id="style_postal_code">
<title>POSTAL_CODE</title>
-<para>.......</para>
+<para>A postal code to associate with a position. It is freeform text and is not used by GPSBabel for any geocoding or such.</para>
<para>example:<screen format="linespecific">POSTAL_CODE, "", "%s"</screen></para>
</section>
<para> This command will read from a Magellan unit attached
to the first serial port on a Linux system (device names will
vary on other OSes; typically COMx: on WIndows) and write them as a geocaching loc file.</para>
+<example>
+ <title>Command showing Linux download from Magellan serial and writing to .loc file</title>
<para><userinput>gpsbabel -i magellan -f /dev/ttyS0 -o geo -F mag.loc</userinput></para>
+</example>
<para>This second command does the same on Microsoft Windows.</para>
+<example>
+ <title>Command showing Windows download from Magellan serial and writing to .loc file</title>
<para><userinput>gpsbabel -i magellan -f com1 -o geo -F mag.loc</userinput></para>
+</example>
<para>Optionally, you may specify <parameter moreinfo="none">-s</parameter> in any command line. This
causes the program to ignore any "short" names that may be
present in the source data format and synthesize one from the
</simplelist>
<para> but GPSBabel is flexible enough to allow more complicated
operations such as reading from several files (potentially of
-different types), applying a filter, reading more data, then write the
+different types), applying a filter, reading more data, then writing the
merged data to multiple destinations.
</para>
<para>The input file type remains unchanged until a new
<parameter moreinfo="none">-i</parameter> argument is seen.
Files are read in the order they appear. So you could merge
three input files into one output file with: </para>
- <para><userinput>gpsbabel -i geo -f 1.loc -f 2.loc -f 3.loc -o geo -F big.loc</userinput></para>
+ <example>
+ <title>Merging multiple files into one</title>
+ <para><userinput>gpsbabel -i geo -f 1.loc -f 2.loc -f 3.loc -o geo -F big.loc</userinput></para>
+ </example>
<para>You can merge files of different types:</para>
- <para><userinput>gpsbabel -i geo -f 1.loc -i gpx -f 2.gpx -i pcx 3.pcx
--o gpsutil -F big.gps</userinput></para>
+ <example>
+ <title>Merging multiple files of differing types.</title>
+ <para><userinput>gpsbabel -i geo -f 1.loc -i gpx -f 2.gpx -i pcx 3.pcx -o gpsutil -F big.gps</userinput></para>
+ </example>
+ <example>
+ <title>Writing the same data in multiple output formats.</title>
<para> You can write the same data in different output formats:</para>
+
<para><userinput>gpsbabel -i geo -f 1.loc -o gpx -F 1.gpx -o pcx -F 1.wpt</userinput></para>
+ </example>
<para>If you want to change the character set of input or/and
output side you can do this with the option <option>-c
<character set></option>. You can get a complete list
There are three optional sections.
<itemizedlist>
<listitem>
- <para>"Common format settings"</para>
+ <para>Common format settings.</para>
<para> Any option from any of the formats listed here will be used by
GPSBabel unless explictly provided on the command line.
</para>
</listitem>
<listitem>
- <para>"Common filter settings"</para>
+ <para>Common filter settings.</para>
<para>As above, but for filters.</para>
</listitem>
<listitem>
output. Additional formats may be added by interested parties
later.
</para>
+<example>
+ <title>Read realtime positioning from Garmin USB, write to Keyhole Markup</title>
<para><userinput>gpsbabel -T -i garmin -f usb: -o kml -F xxx.kml</userinput></para>
+</example>
<para>
Will read the USB-connected Garmin and rewrite 'xxx.kml' atomically,
suitable for a self-refreshing network link in Google Earth.
<para>
- Like GPSBabel <ulink url="http://www.gpsinformation.org/ronh/g7towin.htm">G7ToWin</ulink> is a program which allows uploading and
+ Like GPSBabel
, <ulink url="http://www.gpsinformation.org/ronh/g7towin.htm">G7ToWin</ulink> is a program which allows uploading and
downloading information from several GPS devices (Garmin, Lowrance/Eagle, Magellan).
G7ToWin has its own data format, which is an enhanced format used in Gardown.
</para>
</para>
<para>
We can also read some GPS data (including coordinates) from version 2.5. But
- it seems, that this newer version doesn't more store time stamps. This can be
+ it seems, that this newer version no longer stores time stamps. This can be
a problem when converting to other formats or if you want to use our track filter.
</para>
<para> This format is designed to read the XML emitted when you
-tack "&output=js" onto the end of a <ulink url="http://www.maps.google.com>Google Maps">Google Maps</ulink>route URL (use
+tack "&output=js" onto the end of a <ulink url="http://www.maps.google.com>Google Maps">Google Maps</ulink> route URL (use
the "link to this page" option to get a usable URL.) This allows you
to plan a route using Google Maps, then download it and use it in your
own mapping program or GPS receiver. To get a file suitable for use
--- /dev/null
+<para>
+This is the format for MagicMaps project ikt files
+</para>
<para>
KML, the Keyhole Markup Language, is used by Keyhole and
-<ulink url="http://earth.google.com">Google Earth</ulink>. There are numerous
-features in this file format that GPSBabel
-doesn't support - such as camera views - but core spport waypoints, tracks, and routes work well.
+<ulink url="http://earth.google.com">Google Earth</ulink>.
+</para>
+<para>There are concepts in KML that GPSBabel can't support very well on
+read becuase they don't map well into other programs. For example, KML has
+ideas of camera views and names and descriptions can have arbitrarily
+complicated HTML in them. KML files may have tiered "Styles" which
+can identify sizing info and URLs of associated icons. Reading such
+files with GPSBabel - even if your goal it to out to KML - can often
+have suprising results. Simple files with waypoints and paths (which
+GPSBabel represents internally as tracks) work fine.
</para>
<para>
Google Earth also uses GPSBabel internally for receiver communications
<para>
In general, GPSBabel's KML writer is relatively strong. GPSBabel handles simple KML on read fairly well, but if you're dealing with handcrafted KML that uses extensive features that have no analog in other formats like nested folders, ringgeometry, camera angles, and such, don't expect GPSBabel to do well with them on read.
</para>
+<para>
+ Google Earth 4.0 and later have a feature that can suprise users of this
+ format. Earth's "time slider" feature controls what timestamped data
+ gets displayed. If you're using data that has timestampes (e.g. GPX
+ points that contain time or almost any track data) this will be important
+ to you. The time slider defaults to the far left position and fully closed.
+ This means that only the first data point will be displayed. You can
+ tweak Earth's settings to "view->show time->never" or
+ you can widen the time slider to show the range of data of interest.
+</para>
+<para>
+ See <ulink url="http://earth.google.com/userguide/v4/ug_gps.com#timeline">Google Earth's documentation on timelines</ulink> for more info.
+</para>
-
-
- <para>Support for Kartex 5 trackfiles. For more info see kwf2.</para>
+ <para>Support for Kartex 5 trackfiles. For more info see <link linkend="fmt_kwf2">kwf2</link>.</para>
<para> Input support for Microsoft AutoRoute 2002-2006 .axe files
-and Microsoft Streets and Trips .est files.
+and Microsoft Streets and Trips .est files. This is for reading routes
+created this program and is different than the <link linkend="fmt_s_and_t">
+s_and_t</link> format used for writing pushpins.</para><para>
These files contains only routes. We can extract the coordinates and
the names of the points within route. An export to this format will
not be supported.</para>
<para> Input support for Microsoft AutoRoute 2002-2006 .axe files
-and Microsoft Streets and Trips .est files.
+and Microsoft Streets and Trips .est files. This is for reading routes
+created this program and is different than the <link linkend="fmt_s_and_t">
+s_and_t</link> format used for writing pushpins.</para><para>
These files contains only routes. We can extract the coordinates and
the names of the points within route. An export to this format will
not be supported.</para>
<para>Binary file protocol converter for MTK based GPS loggers.
This format reads the raw binary format created by the MTK Windows application
-and outputs to other gpsbabel supported formats.
-When using the csv option a MTK application compatible output file will also be created.
-
+and outputs to other formats supported by GPSBabel
+When using the csv option a MTK application compatible output file will also be created.</para>
+<para>
It has been tested with <productname>Transystem i-Blue 747</productname> but other devices should
work as well (Qstarz BT-Q1000, iTrek Z1, ...)
-
+</para><para>
All position items (including button push) will be listed as trackpoints in the output.
Log items due to button push are presented as waypoints.
In theory we would not add waypoints to the list of trackpoints. But as the MTK logger restart the
GPSBabel supports the Navilink protocol used by the
<ulink url="http://www.locosystech.com/product.php?zln=en&id=5">Locosys GT-11</ulink>
GPS receivers. These are sold under a variety of names including:
-<simplelist columns="2">
+<simplelist columns="3">
<member>NaviGPS</member>
<member>NaviGPS-BT</member>
<member>GT-11</member>
-
+<para>
+ This option is experimental and was added to solve a very specific problem.
+ Certain Garmin units (the original black and white Vista is known to have
+ this) will sometimes scramble their clock crazy far into the future (like
+ 2066). When this happens, the GPS itself may or may not work and
+ later conversations with GPSBabel may fail as the time overflows the
+ documented range. The use of <option>resettime</option> brings the GPS's internal clock
+ back close enough to reality that the GPS itself can then "fix" it when
+ it has next a lock.
+</para>
<para>
- Garmin unit seems to use the creation timestamp of GPI files for internal purposes.
+ The Garmin units seem to use the creation timestamp of GPI files for internal purposes.
In other words, if you load GPI files with same creation timestamp on your device,
- strange things will happen (missing or repeated POIs). With the sleep option, GPSbabel waits a given
+ strange things will happen, such as having missing or repeated POIs. With the sleep option, GPSBabel waits a given
number of seconds after the GPI file was written.
</para>
<para>
- In the normal case of using GPSBabel from commandline or from the GUI, the chance of creating files
+ In the normal case of using GPSBabel from the command line or from the GUI, the chance of creating files
with the same timestamp is in the nearly ZERO. In scripts or batch files where you are writing multiple files - even from different GPSBabel instances - the odds of this happening is rather good.
The sleep option forces GPSBabel to wait after creating a file to ensure the timestamps are unique. Values are specified in seconds and can be 1 or more.
</para>
</userinput>
</para>
<para>
- Because gdb creates internal a route AND a waypoint list, you have to drop all
- waypoints and transform the route into waypoints. So you'll get a well ordered
- html output. We sugess these steps for all waypoint-only formats as html.
+ Because gdb internally creates a route AND a waypoint list, you have to drop all
+ waypoints and transform the route into waypoints in order to get a well ordered
+ html output. We suggest these steps for all waypoint-only formats as html.
</para>
</example>
-
+<para>
+ When reading <ulink url="http://www.geocaching.com"> Groundspeak Pocket Queries </ulink>, the <option>logpoint</option> option creates additional waypoints from the log entries.
+</para>
+<para>
+ A typical use for this is to get coordinates read from "corrected coordinates" logs.
+</para>
-
+<para>
+ When used with the <option> -s </option> to control shortnames, the snlen suboption to GPX controls how long the generated smartname will be. This can be useful for cases like writing GPX files to a GPS that has a fixed waypoint name length.
+</para>
-
+<para>
+When used with the <option>-s</option> to generate smart shortnames, this suboption controls whether whitespace is allowed in the generated shortnames.
+</para>
+<para>
+ This is a fairly esoteric option. If the GPX file you are reading has only base pathnames (e.g "foo.html") the value you specify to this argument will be prepended to that. For example, "-o gpx,urlbase=c:\My Documents\Whatever" would result in the link to that waypoint being written to refer to <filename>c:\My Document\WHatever\foo.html</filename>
+</para>
-
+<para>
+ The deficon option is used to control the icon output when writing to this format. It overrides any icon informatino that might be present in the source data.
+</para>
-
+<para>
+ The deficon option is used to control the icon output when writing to this format. It overrides any icon informatino that might be present in the source data.
+</para>
-
+<para>
+ If this option is present, retired (archived) caches will be suppressed on write.
+</para>
-
+<para>
+ This option, specified in meters, allows you to set the proximity of
+written in waypoints.
+</para>
-
+<para>
+ This option allows you to specify the length of waypoint names written to this format when used with the <option>-s</option> option.
+</para>
-
+<para>
+ When specified, this option will force the generated waypoint names to be unique.
+</para>
-
+<para>
+ When specified, this option will force generated shortnames to be in all uppercase letters.
+</para>
-
+<para>
+ This option forces waypoint names generated with <option> -s </option> to allow whitespace in the names.
+</para>
-
+<para>
+ This option allows you to specify a background color of a waypoint. You can specify it as either a decimal number or one of the standard web colors.
+</para>
-
+<para>
+ This option allows you to specify a foreground color of a waypoint. You can specify it as either a decimal number or one of the standard web colors.
+</para>
-
+<para>
+ The deficon option is used to control the icon output when writing to this format. It overrides any icon informatino that might be present in the source data.
+</para>
-
+<para>
+ This option allows you to specify the length of waypoint names written to this format when used with the <option>-s</option> option.
+</para>
-
+<para>
+ Carto Exploreur requires a slightly incompatible variation of the PCX format
+when written. Specifying this option on write tells us to create that strain of PCX.
+</para>
-
+<para>
+ The deficon option is used to control the icon output when writing to this format. It overrides any icon informatino that might be present in the source data.
+</para>
-
+<para>
+This options lets you specify an icon for an Ad-hoc, closed, waypoint.
+</para>
+<para>
+This options lets you specify an icon for an Ad-hoc, open, waypoint.
+</para>
-
+<para>
+This option lets you specify an icon for infrastructure closed points.
+</para>
+<para>
+This option lets you specify an icon for infrastructure open points.
+</para>
-
+<para>
+ This options lets you specify that the shortname of the waypoint is the MAC address.
+</para>
<para>
These data files are XML based. Every GPS element (way or node) described by the files has a unique
number as identifier. When we write OSM data files and don't know something about the id's,
- negative numbers will be used as identifier. This has bee
d tested with <ulink url="http://wiki.openstreetmap.org/index.php/JOSM">JOSM</ulink>.
+ negative numbers will be used as identifier. This has bee
n tested with <ulink url="http://wiki.openstreetmap.org/index.php/JOSM">JOSM</ulink>.
</para>
<para>
- Because the resulting timestamps of OSM ways aren't in the manner of real GPS track,
+ Because the resulting timestamps of OSM ways differ from real GPS tracks,
we read OSM ways into routes. On the output side we write all available routes and tracks into the osm target file.
</para>
- <para> This is a format for importing into
+ <para> This is a format for creating data to be read by
<ulink url="http://www.microsoft.com/streets/default.mspx"> Microsoft Streets and
-Trips</ulink>. It's been exercised on versions from 2003 through 2007. Detailed
+Trips</ulink>. It's been exercised on versions from 2003 through 2008. Detailed
instructions on how to use it, including preserving hyperlinks, are at
<ulink url="http://www.gpsbabel.org/formats/s_and_t/Importing_into_Microsoft_Streets_and_Trips_2003.html">gpsbabel.org</ulink>
</para>
+ <para>
+ This format has nothing to do with the <link linkend="fmt_msroute1"> .est/axe format</link> used by this program to store routes.
+ </para>
<para>
Unicsv examines the first line of a file to determine the field
- order and field separator in that file. It is thus read-only format.
+ order and field separator in that file. On write, it tries to
+ figure out what data it has and writes headers and all the data it can.
</para>
<para>
If the first line contains any tabs, the data lines are assumed
- <para> WFFF is the export format for Aspecto Software's WiFiFoFum 2.0 for Windows Mobile PCs.</para>
+ <para> WFFF is the export format for <ulink url="http://www.aspecto-software.com/rw/applications/wififofum/index.html">Aspecto Software's WiFiFoFum</ulink> 2.0 for Windows Mobile PCs.</para>
<para>It is a simple XML format that is read-only to GPSBabel and stores information about a WiFi stumbling session.</para>
<para>All WiFi-specific elements are written in the description field, similar to the netstumbler format.</para>
projects / gpsbabel.git / commitdiff